Skip to main content

CKYC Validation API

This document highlights the CKYC Validation API details.

Table of Contents​

Objective​

The CKYC Validation API verifies a user's personally identifiable information (PII) downloaded from their record in the central KYC registry and classifies the response into the following three buckets based on an internal scoring mechanism.

  • Approve
  • Review
  • Reject
InputOutput
The record of the user from the central KYC registry - the user's selfie, XML file, and officially valid documents.The classification result after matching the user's details across all of these files.

Benefits​

The API verifies the user's PII stored in an XML file in the central KYC registry against their officially valid documents (OVDs) downloaded from the same record. It also verifies if the selfie from the record matches the images present in each OVD file.

info

A Central KYC Registry record consists of a user's PII in an XML file, a selfie and officially valid documents (OVDs) such as Aadhaar, voter ID, passport and driving license in a PDF file. HyperVerge's identity solution supports any of these four OVDs.

caution

You are expected to parse the XML from a user's central KYC registry record, and send the data to the CKYC Validation API along with the selfie and the OVDs downloaded from the same record.

Details​

Scoring Mechanism​

The following table describes the score for each field in the document where there is a mismatch.

ScoringMechanism

For each document, the sum of scores is taken and the minimum document score is considered.

Consider a CKYC X instance where the following discrepancies are present:

  • The Aadhaar document contains an address error.
  • The driving licence document has both a pincode error and an address error.

In this scenario, the scoring is as follows:

  • The total score for the Aadhaar document is 2 (with an address error weighted at 2).
  • The total score for the driving licence document is 3 (with the pincode error weighted at 1 and the address error weighted at 2).

Consequently, the CKYC X instance's final score will be determined by the Aadhaar document, which has the lowest score of 2 in comparison to the scores of other documents.

API URL​

https://ind-ckyc.hyperverge.co/api/v1/validate

Authentication​

You need a unique pair of application ID ( appId ) and application key (appKey) from HyperVerge to verify your identity for accessing the API.

API Request Details​

Method - POST​

Headers​

ParameterMandatory or OptionalTypeDescriptionValid Values
content-typeMandatorystringThis parameter defines the media type for the request payload.multipart/form-data
appIdMandatorystringThe application ID shared by HyperVergeNot Applicable - this is a unique value.
appKeyMandatorystringThe application key shared by HyperVergeNot Applicable - this is a unique value.
transactionIdMandatorystringAny unique ID.Not Applicable - this is a unique value.

Inputs​

ParameterMandatory or OptionalTypeValid ValuesDescription
first_nameOptionalstringNot applicableThe first name of the user.
middle_nameOptionalstringNot applicableThe middle name of the user.
last_nameOptionalstringNot applicableThe last name of the user.
full_nameOptionalstringNot applicableThe full name of the user.
dobOptionalstringNot applicableThe date of birth of the user in the format DD-MM-YYYY.
address1OptionalstringNot applicableThe primary address line of the user.
address2OptionalstringNot applicableThe secondary address line of the user.
address3OptionalstringNot applicableThe tertiary address line of the user.
cityOptionalstringNot applicableThe city of residence of the user.
districtOptionalstringNot applicableThe district of residence of the user.
stateOptionalstringNot applicableThe state of residence of the user.
countryOptionalstringNot applicableThe country of residence of the user.
pincodeOptionalstringNot applicableThe PIN code or postal code of residence of the user.
aadhaarSelectively Optional:
The request should have at least one of the following inputs:
  • voter_id,
  • passport,
  • aadhaar, or
  • driving_license.
stringNot applicableThe Aadhaar number of the user.
driving_licenseSelectively Optional:
The request should have at least one of the following inputs:
  • voter_id,
  • passport,
  • aadhaar, or
  • driving_license.
stringNot applicableThe driving license number of the user.
voter_idSelectively Optional:
The request should have at least one of the following inputs:
  • voter_id,
  • passport,
  • aadhaar, or
  • driving_license.
stringNot applicableThe voter ID number of the user.
passportSelectively Optional:
The request should have at least one of the following inputs:
  • voter_id,
  • passport,
  • aadhaar, or
  • driving_license.
stringNot applicableThe passport number of the user.
panOptionalstringNot applicableThe PAN number of the user.
validate_panOptionalstring"yes" or "no"Indicates whether to validate the PAN number.
mask_aadhaarOptionalstring"yes" or "no"Indicates whether to mask the Aadhaar number.
image_details
Selectively Optional*

This parameter becomes mandatory if the imageDetails parameter is not passed in the request.

file
  • For each image sent in the request, the file name should either have one of the following document names or the its corresponding identifier.
    IdentifierDocument Name
    02Photo
    03PAN
    04Proof of possession of Aadhaar
    05Passport
    06Driving Licence
    07Voters ID
    For example, any one of the following names is acceptable for a request containing an Aadhaar input:
    • aadhaar.pdf
    • xyz_04_.pdf
    • adhaar.pdf
    • xyz_aadhaar.pdf
  • Accepted file formats - JPEG, PNG, TIFF & PDF.
  • Base64 encoding is not accepted.
The image file(s) containing the supporting documents of the user. These will be validated against the input fields in the request. You can also include a file with the image of the user to perform a face match identity authentication. Alternatively, this parameter can be passed as received from the
imageDetails
Selectively Optional*

This parameter becomes mandatory if the image_details parameter is not passed in the request.

objectObject with valid image URL stringsThis parameter allows to send images using urls with acceptable document code. The details obtained from the search and download response, including the code of the kyc document and the url containing the image or the pdf
returnOcrDumpOptionalstring"yes" or "no"If set to 'yes', the response has an additional ocrDump field. It contains a combined string with characters extracted from each file attached to the API request using Optical Character Recognition (OCR).
standardOcrDumpOptionalstring"yes" or "no"If set to 'yes', the response has an additional ocrDump field. It contains a combined string with characters extracted from each file attached to the API request using Optical Character Recognition (OCR).
returnMaskedAadhaarNumberOptionalstring"yes" or "no"If set to "yes", the user's Aadhaar value is masked in the response.
returnInputImageOptionalstring"yes" or "no"If set to "yes", the response will include a key inputImageUrls, which contains the URLs of the input files.
returnSingleMaskedFile
Selectively Optional*
This parameter becomes works only when mask_aadhaar parameter is enabled.
string"yes" or "no"If set to "yes", the response will include a key masked_aadhaar_url, containing a single merged file of the masked Aadhaar documents. If not enabled, the masked files will be returned as individual, unmerged documents by default.

Request​

The following code shows a standard curl request for the API.

curl --location --request POST 'https://ind-ckyc.hyperverge.co/api/v1/validate' \
--header 'Content-Type: multipart/form-data' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--form 'first_name="<Enter_the_firstName>"' \
--form 'last_name="<Enter_the_lastName>"' \
--form 'dob="<Enter_the_DD-MM-YYYY>"' \
--form 'address1="<Enter_the_address1>"' \
--form 'address2="<Enter_the_address2>"' \
--form 'address3="<Enter_the_address3>"' \
--form 'city="<Enter_the_city>"' \
--form 'district="<Enter_the_district>"' \
--form 'state="<Enter_the_state>"' \
--form 'country="<Enter_the_country>"' \
--form 'pincode="<Enter_the_pincode>"' \
--form 'mask_aadhaar="<Enter_yes_or_no>"' \
--form 'image_details=@"<Enter_the_path_to_file>"' \
--form 'image_details=@"<Enter_the_path_to_file>"' \
--form 'image_details=@"<Enter_the_path_to_file>"' \
--form 'pan="<Enter_the_pan>"' \
--form 'validate_pan="<Enter_yes_or_no>"' \
--form 'aadhaar="<Enter_the_aadhaar>"' \
--form 'standardOcrDump="<Enter_yes_or_no>"' \
--form 'returnOcrDump="<Enter_yes_or_no>"'

Success Response​

The following is the structure of a successful response from the API.

{
  "status": "success",
  "statusCode": 200,
  "result": {
    "action": "String",
    "validPOA": ["String"],
    "validPOI": ["String"],
    "invalidDocs": {
      "document": ["error"]
    },
    "details": {
      "document": {
        "field": {
          "matchFound": true,
          "score": 0
        }
      }
    },
    "masked_aadhaar_url": ["String"]
  }
}

Success Response Details​

The following table provides the details of the fields in a success response.

Parameter TypeValid Values Description
action- approve, reject, manual_review
  • approve - Minimum weighted score is less than two
  • reject - Minimum weighted score is greater than three
  • manual_review - Minimum weighted score is equal to two. For more details on the score calculation refer to Weightage table.
validPOA-"passport", "aadhaar", "voter_id", "dl", "pan", "other", "photo", "aadhaar_kyc" Lists all the documents that have succeeded address validation
validPOI-"passport", "aadhaar", "voter_id", "dl", "pan", "other", "photo", "aadhaar_kyc"Lists all the documents that have succeeded identity validation such as name and face match
invalidDocs- Contains a map of the document with the mismatch codes. Valid documents include Aadhaar, passport, driving_license and voter_id.
details

Object document, Object field, matchFound: boolean, score: number.
  • Contains a map of document with individual field status and the match score. Valid documents include aadhaar, passport, driving_license and voter_id.
  • Valid Field names include first_name, middle_name, last_name, full_name, address1, address2, address3, city, district, state, country, pincode, dob, voter_id, aadhaar, passport, driving_license
  • Contains an array of URLs with Aadhaar
masked_aadhaar_urlArray of StringsNot ApplicableThe link to the user's masked Aadhaar image with the first 8 digits masked. It is valid for 15 mins.

Success Responses​

If the status is "success" in the response, the CKYC validation process is complete. The following samples reflect scenarios where the action field is "approve".


The record is approved when all the fields are validated and the total score is less than 2.


{
  "status": "success",
  "statusCode": "200",
  "result": {
    "action": "approve",
    "validPOA": ["aadhaar"],
    "validPOI": ["aadhaar"],
    "invalidDocs": {},
    "details": {
      "aadhaar": {
        "first_name": {
          "matchFound": true,
          "score": 90
        },
        "last_name": {
          "matchFound": true,
          "score": 100
        },
        "address1": {
          "matchFound": true,
          "score": 95
        },
        "address2": {
          "matchFound": true,
          "score": 96
        },
        "address3": {
          "matchFound": true,
          "score": 100
        },
        "city": {
          "matchFound": true,
          "score": 100
        },
        "dob": {
          "matchFound": true,
          "score": 100
        },
        "aadhaar": {
          "matchFound": true,
          "score": 100
        },
        "faceMatch": {
          "matchFound": true,
          "score": 90
        }
      }
    },
    "aadhaar_type": "STANDARD"
  }
}

Failure Response Samples​

Explore failure response scenarios where the 'action' is either 'manual review' or 'reject'.

{
  "status": "success",
  "statusCode": "200",
  "result": {
    "action": "reject",
    "validPOA": [],
    "validPOI": [],
    "invalidDocs": {
      "dl": ["ER_FACE_NO_MATCH", "ER_NAME"]
    },
    "details": {
      "dl": {
        "first_name": {
          "matchFound": false,
          "score": 40
        },
        "last_name": {
          "matchFound": false,
          "score": 60
        },
        "dob": {
          "matchFound": true,
          "score": 100
        },
        "address1": {
          "matchFound": true,
          "score": 100
        },
        "address2": {
          "matchFound": true,
          "score": 100
        },
        "address3": {
          "matchFound": true,
          "score": 100
        },
        "city": {
          "matchFound": true,
          "score": 100
        },
        "faceMatch": {
          "matchFound": false,
          "score": 35
        }
      }
    }
  }
}

Error Responses​

{
  "status": "failure",
  "statusCode": "401",
  "error": "Missing/Invalid credentials"
}
Code property from error objectCategoryDescription
ER_BAD_DOCBad documentDocument is not readable
ER_FACE_NO_MATCHFace mismatchFace Match not found
ER_FACE_MISSINGFace missing
ER_NAMEField mismatchThe name is a mismatch.
ER _ADDRESSThe address is a mismatch.
ER_DOBThe date of birth is a mismatch.
ER_IDThe ID number is a mismatch.
ER_PINCODEThe pin code does not match.
ER_SERVERFile size exceeds the limitFile size exceeds 6MB.
ER_SERVERDocument length exceeds the limitThe document exceeds 5 pages.
Status CodeError MessageDescription
401Missing/Invalid credentials You have either missed to include the appid and appkey credentials in the request header or you have provided incorrect values.
400first_name should not be null or undefined You have missed to send the mandatory parameters in the request.
400Selfie image not sent as part of the payload You have missed to send the selfie image in the request.
400pages exceeded the supported length of 5 The number of pages in the request document exceeds 5 pages.
413File too large This status code is returned for requests with a file size exceeding 6MB.
5xxInternal server errorThis status code is returned for server errors. Kindly reach out to HyperVerge.
The following are other sample error responses for your reference.
{
  "status": "fail",
  "statusCode": "400",
  "error": {
    "code": "ER_REQ_VALIDATE",
    "message": "first_name should not be null or undefined"
  }
}
Was this helpful?
ON THIS PAGE
Ask AIBeta
Hi! How can I help?
Ask me anything about HyperVerge products, APIs, and SDKs.
Try asking: